Booking Appointment Workflow

Bookadoc integrates with DrChrono to allow patients to schedule appointments with healthcare providers. This process involves validating available slots, creating appointments, and ensuring synchronization between both systems.

The booking workflow consists of the following steps:

1. Validate input data (patient ID, provider ID, department ID, appointment type ID)
2. Check if the appointment slot is available
3. Create the appointment in AthenaHealth
4. Store appointment details in Bookadoc
5. Return confirmation to the patient

---

Step 1: Validate Input Data

Before booking an appointment, Bookadoc ensures that all required fields are provided.

Required Fields

Field	Description
patientid	The unique ID of the patient in AthenaHealth
doctorid	The ID of the healthcare provider
officeid	The department where the appointment will take place

If any of these fields are missing, Bookadoc returns an error message prompting the user to provide the necessary details.

---

Step 2: Check Slot Availability

Before creating an appointment, Bookadoc checks whether the selected slot is open.

API Endpoint

GET /api/availability?date=DATE&office=OFFICE_ID

Example Request

GET /api/availability?date=2025-02-18&office=123456

Response Example

{
  "duration": 30,
  "date": "2025-02-18",
  "open_slots": [
    "start": "00:00",
    "end": "23:00",
    "availability": [
      {
        "start": "00:00",
        "end": "00:30"
      },
      ...
    ],
    "office": 123456
  ]
}

To get the OFFICE_ID for this request to be made, use the API endpoint below:

Office API Endpoint

GET /api/offices

---

Step 3: Create the Appointment

Once the slot is confirmed to be open, Bookadoc sends a request to DrChrono to create the appointment.

API Endpoint

POST /api/appointments

Request Payload

{
  "doctor": 123456,
  "exam_room": 0,
  "office": 234567,
  "patient": 345678900,
  "scheduled_time": "2025-02-21T14:00",
  "duration": 30
}

The duration field is only required if appointment profile id has not been provided. The request payload properties above are required before you can book an appointment.

To get the doctor id for the POST request to be made, use the API endpoint below:

Doctor API Endpoint

GET /api/doctors

To get the exam_room index for the POST request to be made. It is usually returned after a GET request has been made with Office API Endpoint

To get the patient id for the POST request to be made, use the API endpoint below:

Patient API Endpoint

GET /api/patients

Also the duration integer property value represents the duration for the booking in minutes.

Response Example

{ 
  "allow_overlapping": false,
  "appt_is_break": false,
  "base_recurring_appointment": null,
  "clinical_note": null,
  "color": null,
  "created_at": "2025-02-20T11:56:42",
  "created_by": "SIGNED_IN_USER",
  "custom_fields": [],
  "custom_status": null,
  "custom_vitals": [],
  "deleted_flag": false,
  "doctor": 511718,
  "duration": 30,
  "exam_room": 1,
  "icd10_codes": [],
  "id": "342545447",
  "ins1_status": "",
  "ins2_status": "",
  "is_walk_in": false,
  "is_virtual_base": false,
  "notes": "",
  "office": 540214,
  "patient": 125651758,
  "payment_profile": "Cash",
  "profile": null,
  "reason": "",
  "recur_end_date": null,
  "recur_start_date": null,
  "recurring_appointment": false,
  "recurring_days": [],
  "recurs_every": 1,
  "reminders": [],
  "scheduled_time": "2025-02-21T14:00:00",
  "status": "",
  "status_transitions": [],
  "updated_at": "2025-02-20T11:56:42",
  "vitals": {
    "height": null,
    "weight": null,
    "bmi": null,
    "blood_pressure_1": null,
    "blood_pressure_2": null,
    "temperature": null,
    "pulse": null,
    "respiratory_rate": null,
    "oxygen_saturation": null,
    "pain": null,
    "smoking_status": "blank",
    "head_circumference":null,
    "head_circumference_units": "inches",
    "height_units": "inches",
    "temperature_units": "f",
    "weight_units": "lbs"
    },
  "extended_updated_at": "2025-02-20T11:56:42",
  "is_telehealth": false,
  "telehealth_url": null
}

If the request is successful, the appointment is created in DrChrono, and Bookadoc records the appointment details.

---

Step 4: Store Appointment Details in Bookadoc

After the appointment is booked in DrChrono, Bookadoc saves the appointment data in its system to ensure synchronization.

Stored Information

• Appointment ID
• Patient details
• Provider information
• Appointment date and time
• Status (confirmed)

This allows Bookadoc to display upcoming appointments to patients and providers.

---

Step 5: Return Confirmation to Patient

Once the booking is successful, Bookadoc provides a confirmation message to the patient.

Example Confirmation Message

{
  "message": "Your appointment has been successfully booked.",
  "appointmentDetails": {
    "appointmentId": "1861676",
    "date": "02/07/2025",
    "time": "08:00 AM",
    "provider": "Dr. John Doe"
  }
}

Patients receive this confirmation via the Bookadoc platform and (if enabled) email or SMS notifications.

---

Error Handling

If an error occurs at any step, Bookadoc handles it gracefully and provides feedback to the user.

Common Errors & Resolutions

Error Code	Description	Resolution
400 Bad Request	Missing or invalid input fields	Ensure all required fields are provided
409 Conflict	Appointment slot already booked	Prompt user to select another slot
500 Internal Server Error	AthenaHealth API issue	Retry the request after some time

---

Conclusion

The booking appointment workflow ensures that Bookadoc synchronizes seamlessly with DrChrono, allowing patients to book available slots while keeping providers' schedules up to date. By validating data, checking availability, and handling errors effectively, Bookadoc enhances the booking experience for both patients and providers.

---